home *** CD-ROM | disk | FTP | other *** search
/ AGA Toolkit '97 / The AGA Toolkit '97.iso / workbench / blanker / multiblank / developers / developer.doc next >
Text File  |  1996-09-07  |  3KB  |  67 lines
  1. Writing a module for MBlank is quite simple.  Your code must perform a few
  2. basic functions but the rest is up to you.
  3.  
  4. 1. When your module is run it must create a public message port with the
  5.    name "MBlank" and then wait for messages from MultiBlank.  MultiBlank uses
  6.    the creation of the port as an indicator that everything went well and
  7.    that the module is ready to go.
  8.  
  9. 2. MultiBlank trys to keep it's messages coherent but this is not guaranteed
  10.    so I suggest that variables set in the "blanking" procedure are unset in
  11.    that "clearing" procedure, e.g. screen pointers, and tested for validity
  12.    before use.
  13.  
  14. 3. Names for pref files should be derived from the program name returned by
  15.    DOS's GetProgramName ().  This is because the user might want several
  16.    copies of your module with different settings, e.g. my execution module.
  17.  
  18. 4. If your blanking procedure uses a loop then check for signals from the
  19.    port as often as possible using SetSignal () and try to respond quickly.
  20.  
  21. 5. You should also check for SIGBREAKF_CTRL_C so that a module can be stopped
  22.    if run from a CLI by accident.
  23.  
  24. The messages you will recieve are as follows:
  25.  
  26. MBMT_INIT   - initiate any resources your module requires.  Doing it this way
  27.               provides for easier interaction with MultiBlank.  Set the
  28.               "success" field to TRUE or FALSE depending on success and the
  29.               "flags" field depending on availablity of the info and config
  30.               functions. If the module fails you will be sent a MBMT_QUIT
  31.               message straight away. This is why varibles should always be
  32.               set and cleared.
  33.  
  34. MBMT_BLANK  - start the blanking procedure.  Allocate anything needed temp.
  35.               like screens and windows.  Set the "success" field.
  36.  
  37. MBMT_CLEAR  - unblank the screen.  Deallocate anything allocated in the
  38.               blanking procedure.
  39.  
  40. MBMT_INFO   - put the module information requester up.  The message contains
  41.               pointers to MultiBlank's screen and window.  The requester
  42.               should use these as in the example.  Again, the "success" field
  43.               requires setting before you Reply ().  On failure MultiBlank
  44.               puts it's own requester up.  The requesters title should be
  45.               "Module Information"
  46.  
  47. MBMT_CONFIG - put up the module config window.  Much like MBMT_INFO but you
  48.               will probably be using a window of you own, not a requester.
  49.               Use the screen and window fields to centre your window on
  50.               MultiBlank's.  "success" requires setting.  The title is up to
  51.               you but I suggest the module's real name (not the one from
  52.               GetProgramName ()).
  53.  
  54. MBMT_QUIT   - Deallocate resources allocated in MBMT_INIT and remove message
  55.               port then quit.
  56.  
  57. When it's finished copy it to your module directory with the extention
  58. ".mbmod"
  59.  
  60. To program a safe module use the philosophy of "check everything".  Your
  61. module will not be sent MBMT_INFO or MBMT_CONFIG unless you set the "flags"
  62. field in the MBMT_INIT message accordingly.
  63.  
  64. The example code and include file should answer any questions, but I have an
  65. email address if you need more help.
  66.  
  67. Simon